Windows Azure Storage : Message Operations (part 2) - Get Messages

2. Get Messages

In the previous section, you learned to send messages to queues in the Queue service. In this section, you learn to retrieve these messages using the Get Messages operation. The URI for the Get Messages operation is of the format account name>.queue.core.windows.net/<queue name>/messages. The URI for the Get Messages operation supports additional optional parameters, as listed in Table 3.

Listing 4 shows the REST API request for the Get Messages operation.

Example 4. Get Messages REST Request

GET /myfirstazurequeue/messages?numofmessages=10&visibilitytimeout=60&timeout=30_
 HTTP/1.1
x-ms-date: Thu, 18 Jun 2009 05:34:13 GMT
Authorization: SharedKey proazurestorage:qB9P717GTC6nd6rX4Ed16r6QkxO2QwJxLcr
Host: proazurestorage.queue.core.windows.net

					  

In Listing 4, the URI points to the myfirstazurequeue queue. numofmessages=10 instructs the Queue service to retrieve only 10 messages. visibilitytimeout=60 instructs the Queue service to make the retrieved messages invisible to other applications for 60 seconds, unless the receiving application deletes them. Listing 5 shows the REST API response from the Queue service for the Get Messages operation.

Example 5. Get Messages REST Response

HTTP/1.1 200 OK
Content-Type: application/xml
Server: Queue Service Version 1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: c10542ae-fa9e-45fd-b036-3f0b77ed611e
Date: Thu, 18 Jun 2009 05:35:43 GMT
Content-Length: 3900

<?xml version="1.0" encoding="utf-8"?>
<QueueMessagesList>

<QueueMessage>
<MessageId>ba16723c-8b4c-48dd-9d80-d5d2731bcbd8</MessageId>
<InsertionTime>Thu, 18 Jun 2009 05:36:43 GMT</InsertionTime>
<ExpirationTime>Thu, 18 Jun 2009 05:37:28 GMT</ExpirationTime>
<PopReceipt>AgAAAAEAAAAAAAAAIBeHw9bvyQE=</PopReceipt>
<TimeNextVisible>Thu, 18 Jun 2009 05:36:43 GMT</TimeNextVisible>
<MessageText>bXlmaXJzdGF6dXJlbWVzc2FnZQ==</MessageText>
</QueueMessage>
<QueueMessage>
<MessageId>c0d92c72-2f9f-4c15-a177-7cf988c2532d</MessageId>
<InsertionTime>Thu, 18 Jun 2009 05:36:43 GMT</InsertionTime>
<ExpirationTime>Thu, 18 Jun 2009 05:37:28 GMT</ExpirationTime>
<PopReceipt>AgAAAAEAAAAAAAAAIBeHw9bvyQE=</PopReceipt>
<TimeNextVisible>Thu, 18 Jun 2009 05:36:43 GMT</TimeNextVisible>
<MessageText>bXlmaXJzdGF6dXJlbWVzc2FnZQ==</MessageText>
</QueueMessage>
<QueueMessage>
<MessageId>f3ae9ccd-b97c-4bae-bc22-744cadd2c9c0</MessageId>
<InsertionTime>Thu, 18 Jun 2009 05:36:43 GMT</InsertionTime>
<ExpirationTime>Thu, 18 Jun 2009 05:37:28 GMT</ExpirationTime>
<PopReceipt>AgAAAAEAAAAAAAAAIBeHw9bvyQE=</PopReceipt>
<TimeNextVisible>Thu, 18 Jun 2009 05:36:43 GMT</TimeNextVisible>
<MessageText>bXlmaXJzdGF6dXJlbWVzc2FnZQ==</MessageText>
</QueueMessage>
</QueueMessagesList>

					  

Listing 5 shows the HTTP header and body of the Get Messages operation response. For the sake of brevity, only three messages are shown. The HTTP response body consists of a list of messages in XML format. Every <QueueMessage /> element represents a message. When you retrieve a message, the MessageId and the PopReceipt properties of the message are important for deletion purposes. The recommended pattern is to receive the message, process it, and then delete it before it becomes visible to other applications when the visibilitytimeout period expires. The TimeNextVisible value specifies the expiration time of the visibilitytimeout period. The ExpirationTime specifies the time when the message will be marked for deletion if not retrieved and/or deleted by a receiving application. This value was set when the message was sent to the queue. Figure 3 shows the working of the Get Messages operation in the Windows Azure Storage Operations.exe application.

Figure 3. Get Messages in the Windows Azure Storage Operations application

As illustrated in Figure 3, you can use the Get Messages operation for a queue using the Windows Azure Storage Operations application. The steps for retrieving messages are as follows:

The retrieved messages are populated in the DataGridView control in the Messages section. Each message is represented by a row in the DataGridView control. The control displays all the properties of the retrieved messages. To delete a message, select a row in the DataGridView and press the Delete button on your keyboard.

The WindowsAzureStorage.cs file in the Windows Azure Storage Operations project consists of a GetMessages() method, as shown in Listing 6.

Example 6. GetMessages() Method in WindowsAzureStorage.cs

private void GetMessages()
{
dgvMessages.Rows.Clear();
IEnumerable<Microsoft.Samples.ServiceHosting.StorageClient.Message>
 msgs = StorageHelper.GetMessages(txtQueueName.Text, int.Parse(txtNumberOf
Messages.Text), int.Parse(txtVisibilityTimeoutSecs.Text));

if (msgs != null)
{
IList<Microsoft.Samples.ServiceHosting.StorageClient.Message> messages =
new List<Microsoft.Samples.ServiceHosting.StorageClient.Message>(msgs);
PopulateMessagesDataGridView(messages);

}
}

As shown in Listing 6, the GetMessages() method calls the GetMessages() method of WindowsAzureStorageHelper (StorageHelper object). The numofmessages and visibilitytimeout parameters are parsed appropriately into integer values and passed as parameters to the GetMessages() method. The returned messages are then packaged into a list and passed to the PopulateMessagedataGridView() method for display. Figure 4 illustrates the sequence diagram for the Get Messages operation.

Figure 4. Get Messages sequence diagram

As shown in Figure 4, the Windows Azure Storage Operations application calls the GetMessages() method on the WindowsStorageHelper object in the ProAzureCommonLib.dll. The WindowsStorageHelper object calls the GetQueue() method on the QueueStorage object to get an instance of the MessageQueue object. The WindowsStorageHelper object then calls the GetMessages() method on the MessageQueue object. The MessageQueue object calls a private method InternalGet() to retrieve the messages from the specified queue. The body of the HTTP response contains messages in XML format. The XML contents are parsed and packaged into an IEnumerable<Message> collection and passed as a return parameter to the GetMessages() operation. Finally, the Windows Azure Storage Operations application displays these messages in a DataGridView control, as shown earlier in this section.

2.1. Message Event

The StorageClient API also supports an event-driven model for retrieving messages from a queue. The MessageQueue class defines an event called MessageReceived that you can subscribe to. The MessageQueue class also defines two methods StartReceiving() and StopReceiving() that start and stop the event subscription, respectively. The property PollInterval specifies the polling interval in milliseconds. Based on the PollInterval value, a thread calls the Get Messages operation periodically and returns the messages as parameters of the event delegate.

The steps for implementing an event-driven approach to the Get Messages operation are as follows.